<html>
  <head>
    <title>RabbitMQ Management HTTP API</title>
    <style>
      body { font: 12px Verdana,sans-serif; color: #444; padding: 8px 35px; }
      td, th { font: 12px Verdana,sans-serif; color: #444; }
      h1 { font-size: 2em; }
      h2 { font-size: 1.5em; }
      td.path { font-family: monospace; }
      th { font-size 1em; font-weight: bold; }
      table { border-collapse: collapse; }
      table th, table td { vertical-align: top; border: 1px solid #bbb; padding: 5px; }
      code { background: #ffa; }
      pre { background: black; color: #0f0; padding: 10px; word-wrap: break-word;}
      table pre { background: #ffa; color: black; }
    </style>
  </head>
  <body>
    <h1>RabbitMQ Management HTTP API</h1>

    <h2>Introduction</h2>

    <p>Apart from this help page, all URIs will serve only resources
    of type <code>application/json</code>, and will require HTTP basic
    authentication (using the standard RabbitMQ user database). The
    default user is guest/guest.</p>

    <p>Many URIs require the name of a virtual host as part of the
    path, since names only uniquely identify objects within a virtual
    host. As the default virtual host is called "<code>/</code>", this
    will need to be encoded as "<code>%2f</code>".</p>

    <p>PUTing a resource creates it. The JSON object you upload must
    have certain mandatory keys (documented below) and may have
    optional keys. Other keys are ignored. Missing mandatory keys
    constitute an error.</p>

    <p>Since bindings do not have names or IDs in AMQP we synthesise
    one based on all its properties. Since predicting this name is
    hard in the general case, you can also create bindings by POSTing
    to a factory URI. See the example below.</p>

    <p>Many URIs return lists. Such URIs can have the query string
    parameters <code>sort</code> and <code>sort_reverse</code>
    added. <code>sort</code> allows you to select a primary field to
    sort by, and <code>sort_reverse</code> will reverse the sort order
    if set to <code>true</code>. The <code>sort</code> parameter can
    contain subfields separated by dots. This allows you to sort by a
    nested component of the listed items; it does not allow you to
    sort by more than one field. See the example below.</p>

    <p>You can also restrict what information is returned per item
    with the <code>columns</code> parameter. This is a comma-separated
    list of subfields separated by dots. See the example below.</p>

    <p>Most of the GET queries return many fields per
    object. See <a href="/doc/stats.html">the separate stats
    documentation</a>.</p>
    
    <h2>Examples</h2>

    <p>A few quick examples for Windows and Unix, using the command line
    tool <code>curl</code>:</p>

    <ul>
      <li>
        Get a list of vhosts:
<pre>:: Windows
C:\&gt; curl -i -u guest:guest http://localhost:15672/api/vhosts

# Unix
$ curl -i -u guest:guest http://localhost:15672/api/vhosts

HTTP/1.1 200 OK
Server: MochiWeb/1.1 WebMachine/1.10.0 (never breaks eye contact)
Date: Mon, 16 Sep 2013 12:00:02 GMT
Content-Type: application/json
Content-Length: 30

[{"name":"/","tracing":false}]
</pre>
      </li>
      <li>
        Get a list of channels, fast publishers first, restricting the info
        items we get back:
<pre>:: Windows
C:\&gt; curl -i -u guest:guest "http://localhost:15672/api/channels?sort=message_stats.publish_details.rate&amp;sort_reverse=true&amp;columns=name,message_stats.publish_details.rate,message_stats.deliver_get_details.rate"

# Unix
$ curl -i -u guest:guest 'http://localhost:15672/api/channels?sort=message_stats.publish_details.rate&amp;sort_reverse=true&amp;columns=name,message_stats.publish_details.rate,message_stats.deliver_get_details.rate'

HTTP/1.1 200 OK
Server: MochiWeb/1.1 WebMachine/1.10.0 (never breaks eye contact)
Date: Mon, 16 Sep 2013 12:01:17 GMT
Content-Type: application/json
Content-Length: 219
Cache-Control: no-cache

[{"message_stats":{"publish_details":{"rate" <i>... (remainder elided)</i></pre>
      </li>
      <li>
        Create a new vhost:
<pre>:: Windows
C:\&gt; curl -i -u guest:guest -H "content-type:application/json" ^
      -XPUT http://localhost:15672/api/vhosts/foo

# Unix
$ curl -i -u guest:guest -H "content-type:application/json" \
   -XPUT http://localhost:15672/api/vhosts/foo

HTTP/1.1 204 No Content
Server: MochiWeb/1.1 WebMachine/1.10.0 (never breaks eye contact)
Date: Mon, 16 Sep 2013 12:03:00 GMT
Content-Type: application/json
Content-Length: 0</pre>
        <p>Note: you must specify <code>application/json</code> as the
        mime type.</p>
        <p>Note: the name of the object is not needed in the JSON
          object uploaded, since it is in the URI. As a virtual host
          has no properties apart from its name, this means you do not
          need to specify a body at all!</p>
      </li>
      <li>
        Create a new exchange in the default virtual host:
<pre>:: Windows
C:\&gt; curl -i -u guest:guest -H "content-type:application/json" ^
       -XPUT -d"{""type"":""direct"",""durable"":true}" ^
       http://localhost:15672/api/exchanges/%2f/my-new-exchange

# Unix
$ curl -i -u guest:guest -H "content-type:application/json" \
    -XPUT -d'{"type":"direct","durable":true}' \
    http://localhost:15672/api/exchanges/%2f/my-new-exchange

HTTP/1.1 204 No Content
Server: MochiWeb/1.1 WebMachine/1.10.0 (never breaks eye contact)
Date: Mon, 16 Sep 2013 12:04:00 GMT
Content-Type: application/json
Content-Length: 0</pre>
        <p>Note: we never return a body in response to a PUT or
        DELETE, unless it fails.</p>
      </li>
      <li>
        And delete it again:
<pre>:: Windows
C:\&gt; curl -i -u guest:guest -H "content-type:application/json" ^
       -XDELETE http://localhost:15672/api/exchanges/%2f/my-new-exchange

# Unix
$ curl -i -u guest:guest -H "content-type:application/json" \
    -XDELETE http://localhost:15672/api/exchanges/%2f/my-new-exchange

HTTP/1.1 204 No Content
Server: MochiWeb/1.1 WebMachine/1.10.0 (never breaks eye contact)
Date: Mon, 16 Sep 2013 12:05:30 GMT
Content-Type: application/json
Content-Length: 0</pre>
      </li>
    </ul>

    <h2>Reference</h2>

    <table>
      <tr>
        <th>GET</th>
        <th>PUT</th>
        <th>DELETE</th>
        <th>POST</th>
        <th>Path</th>
        <th>Description</th>
      </tr>
      <tr>
        <td>X</td>
        <td></td>
        <td></td>
        <td></td>
        <td class="path">/api/overview</td>
        <td>Various random bits of information that describe the whole
        system.</td>
      </tr>
      <tr>
        <td>X</td>
        <td>X</td>
        <td></td>
        <td></td>
        <td class="path">/api/cluster-name</td>
        <td>Name identifying this RabbitMQ cluster.</td>
      </tr>
      <tr>
        <td>X</td>
        <td></td>
        <td></td>
        <td></td>
        <td class="path">/api/nodes</td>
        <td>A list of nodes in the RabbitMQ cluster.</td>
      </tr>
      <tr>
        <td>X</td>
        <td></td>
        <td></td>
        <td></td>
        <td class="path">/api/nodes/<i>name</i></td>
        <td>
          An individual node in the RabbitMQ cluster. Add
          "?memory=true" to get memory statistics, and "?binary=true"
          to get a breakdown of binary memory use (may be expensive if
          there are many small binaries in the system).
        </td>
      </tr>
      <tr>
        <td>X</td>
        <td></td>
        <td></td>
        <td></td>
        <td class="path">/api/extensions</td>
        <td>A list of extensions to the management plugin.</td>
      </tr>
      <tr>
        <td>X</td>
        <td></td>
        <td></td>
        <td>X</td>
        <td class="path">/api/definitions<br/>
                         /api/all-configuration <em>(deprecated)</em>
        </td>
        <td>
          The server definitions - exchanges, queues, bindings, users,
          virtual hosts, permissions and parameters. Everything apart from
          messages. POST to upload an existing set of definitions. Note
          that:
          <ul>
            <li>
              The definitions are merged. Anything already existing on
              the server but not in the uploaded definitions is
              untouched.
            </li>
            <li>
              Conflicting definitions on immutable objects (exchanges,
              queues and bindings) will cause an error.
            </li>
            <li>
              Conflicting definitions on mutable objects will cause
              the object in the server to be overwritten with the
              object from the definitions.
            </li>
            <li>
              In the event of an error you will be left with a
              part-applied set of definitions.
            </li>
          </ul>
          For convenience you may upload a file from a browser to this
          URI (i.e. you can use <code>multipart/form-data</code> as
          well as <code>application/json</code>) in which case the
          definitions should be uploaded as a form field named
          "file".
        </td>
      </tr>
      <tr>
        <td>X</td>
        <td></td>
        <td></td>
        <td></td>
        <td class="path">/api/connections</td>
        <td>A list of all open connections.</td>
      </tr>
      <tr>
        <td>X</td>
        <td></td>
        <td>X</td>
        <td></td>
        <td class="path">/api/connections/<i>name</i></td>
        <td>
          An individual connection. DELETEing it will close the
          connection. Optionally set the "X-Reason" header when
          DELETEing to provide a reason.
        </td>
      </tr>
      <tr>
        <td>X</td>
        <td></td>
        <td></td>
        <td></td>
        <td class="path">/api/connections/<i>name</i>/channels</td>
        <td>
          List of all channels for a given connection.
        </td>
      </tr>
      <tr>
        <td>X</td>
        <td></td>
        <td></td>
        <td></td>
        <td class="path">/api/channels</td>
        <td>A list of all open channels.</td>
      </tr>
      <tr>
        <td>X</td>
        <td></td>
        <td></td>
        <td></td>
        <td class="path">/api/channels/<i>channel</i></td>
        <td>Details about an individual channel.</td>
      </tr>
      <tr>
        <td>X</td>
        <td></td>
        <td></td>
        <td></td>
        <td class="path">/api/consumers</td>
        <td>A list of all consumers.</td>
      </tr>
      <tr>
        <td>X</td>
        <td></td>
        <td></td>
        <td></td>
        <td class="path">/api/consumers/<i>vhost</i></td>
        <td>A list of all consumers in a given virtual host.</td>
      </tr>
      <tr>
        <td>X</td>
        <td></td>
        <td></td>
        <td></td>
        <td class="path">/api/exchanges</td>
        <td>A list of all exchanges.</td>
      </tr>
      <tr>
        <td>X</td>
        <td></td>
        <td></td>
        <td></td>
        <td class="path">/api/exchanges/<i>vhost</i></td>
        <td>A list of all exchanges in a given virtual host.</td>
      </tr>
      <tr>
        <td>X</td>
        <td>X</td>
        <td>X</td>
        <td></td>
        <td class="path">/api/exchanges/<i>vhost</i>/<i>name</i></td>
        <td>
          An individual exchange. To PUT an exchange, you will need a body looking something like this:
          <pre>{"type":"direct","auto_delete":false,"durable":true,"internal":false,"arguments":{}}</pre>
          The <code>type</code> key is mandatory; other keys are optional.
          <p>
            When DELETEing an exchange you can add the query string
            parameter <code>if-unused=true</code>. This prevents the
            delete from succeeding if the exchange is bound to a queue
            or as a source to another exchange.
          </p>
        </td>
      </tr>
      <tr>
        <td>X</td>
        <td></td>
        <td></td>
        <td></td>
        <td class="path">/api/exchanges/<i>vhost</i>/<i>name</i>/bindings/source</td>
        <td>A list of all bindings in which a given exchange is the source.</td>
      </tr>
      <tr>
        <td>X</td>
        <td></td>
        <td></td>
        <td></td>
        <td class="path">/api/exchanges/<i>vhost</i>/<i>name</i>/bindings/destination</td>
        <td>A list of all bindings in which a given exchange is the destination.</td>
      </tr>
      <tr>
        <td></td>
        <td></td>
        <td></td>
        <td>X</td>
        <td class="path">/api/exchanges/<i>vhost</i>/<i>name</i>/publish</td>
        <td>
          Publish a message to a given exchange. You will need a body
          looking something like:
          <pre>{"properties":{},"routing_key":"my key","payload":"my body","payload_encoding":"string"}</pre>
          All keys are mandatory. The <code>payload_encoding</code>
          key should be either "string" (in which case the payload
          will be taken to be the UTF-8 encoding of the payload field)
          or "base64" (in which case the payload field is taken to be
          base64 encoded).<br/>
          If the message is published successfully, the response will
          look like:
          <pre>{"routed": true}</pre>
          <code>routed</code> will be true if the message was sent to
          at least one queue.
          <p>
            Please note that the HTTP API is not ideal for high
            performance publishing; the need to create a new TCP
            connection for each message published can limit message
            throughput compared to AMQP or other protocols using
            long-lived connections.
          </p>
        </td>
      </tr>
      <tr>
        <td>X</td>
        <td></td>
        <td></td>
        <td></td>
        <td class="path">/api/queues</td>
        <td>A list of all queues.</td>
      </tr>
      <tr>
        <td>X</td>
        <td></td>
        <td></td>
        <td></td>
        <td class="path">/api/queues/<i>vhost</i></td>
        <td>A list of all queues in a given virtual host.</td>
      </tr>
      <tr>
        <td>X</td>
        <td>X</td>
        <td>X</td>
        <td></td>
        <td class="path">/api/queues/<i>vhost</i>/<i>name</i></td>
        <td>
          An individual queue. To PUT a queue, you will need a body looking something like this:
          <pre>{"auto_delete":false,"durable":true,"arguments":{},"node":"rabbit@smacmullen"}</pre>
          All keys are optional.
          <p>
            When DELETEing a queue you can add the query string
            parameters <code>if-empty=true</code> and /
            or <code>if-unused=true</code>. These prevent the delete
            from succeeding if the queue contains messages, or has
            consumers, respectively.
          </p>
        </td>
      </tr>
      <tr>
        <td>X</td>
        <td></td>
        <td></td>
        <td></td>
        <td class="path">/api/queues/<i>vhost</i>/<i>name</i>/bindings</td>
        <td>A list of all bindings on a given queue.</td>
      </tr>
      <tr>
        <td></td>
        <td></td>
        <td>X</td>
        <td></td>
        <td class="path">/api/queues/<i>vhost</i>/<i>name</i>/contents</td>
        <td>Contents of a queue. DELETE to purge. Note you can't GET this.</td>
      </tr>

      <tr>
        <td></td>
        <td></td>
        <td></td>
        <td>X</td>
        <td class="path">/api/queues/<i>vhost</i>/<i>name</i>/actions</td>
        <td>
          Actions that can be taken on a queue. POST a body like:
          <pre>{"action":"sync"}</pre> Currently the actions which are
          supported are <code>sync</code> and <code>cancel_sync</code>.
        </td>
      </tr>

      <tr>
        <td></td>
        <td></td>
        <td></td>
        <td>X</td>
        <td class="path">/api/queues/<i>vhost</i>/<i>name</i>/get</td>
        <td>
          Get messages from a queue. (This is not an HTTP GET as it
          will alter the state of the queue.) You should post a body looking like:
          <pre>{"count":5,"requeue":true,"encoding":"auto","truncate":50000}</pre>
          <ul>
            <li><code>count</code> controls the maximum number of
            messages to get. You may get fewer messages than this if
            the queue cannot immediately provide them.</li>
            <li><code>requeue</code> determines whether the messages will be
            removed from the queue. If requeue is true they will be requeued -
            but their <code>redelivered</code> flag will be set.</li>
            <li><code>encoding</code> must be either "auto" (in which case the
            payload will be returned as a string if it is valid UTF-8, and
            base64 encoded otherwise), or "base64" (in which case the payload
            will always be base64 encoded).</li>
            <li>If <code>truncate</code> is present it will truncate the
            message payload if it is larger than the size given (in bytes).</li>
          </ul>
          <p><code>truncate</code> is optional; all other keys are mandatory.</p>
          <p>
            Please note that the get path in the HTTP API is intended
            for diagnostics etc - it does not implement reliable
            delivery and so should be treated as a sysadmin's tool
            rather than a general API for messaging.
          </p>
        </td>
      </tr>
      <tr>
        <td>X</td>
        <td></td>
        <td></td>
        <td></td>
        <td class="path">/api/bindings</td>
        <td>A list of all bindings.</td>
      </tr>
      <tr>
        <td>X</td>
        <td></td>
        <td></td>
        <td></td>
        <td class="path">/api/bindings/<i>vhost</i></td>
        <td>A list of all bindings in a given virtual host.</td>
      </tr>
      <tr>
        <td>X</td>
        <td></td>
        <td></td>
        <td>X</td>
        <td class="path">/api/bindings/<i>vhost</i>/e/<i>exchange</i>/q/<i>queue</i></td>
        <td>A list of all bindings between an exchange and a
        queue. Remember, an exchange and a queue can be bound
        together many times! To create a new binding, POST to this
        URI. You will need a body looking something like this:
          <pre>{"routing_key":"my_routing_key","arguments":{}}</pre>
          All keys are optional.
          The response will contain a <code>Location</code> header
          telling you the URI of your new binding.
        </td>
      </tr>
      <tr>
        <td>X</td>
        <td></td>
        <td>X</td>
        <td></td>
        <td class="path">/api/bindings/<i>vhost</i>/e/<i>exchange</i>/q/<i>queue</i>/<i>props</i></td>
        <td>An individual binding between an exchange and a queue.
        The <i>props</i> part of the URI is a "name" for the binding
        composed of its routing key and a hash of its arguments.</td>
      </tr>
      <tr>
        <td>X</td>
        <td></td>
        <td></td>
        <td>X</td>
        <td class="path">/api/bindings/<i>vhost</i>/e/<i>source</i>/e/<i>destination</i></td>
        <td>
          A list of all bindings between two exchanges. Similar to
          the list of all bindings between an exchange and a queue,
          above.
        </td>
      </tr>
      <tr>
        <td>X</td>
        <td></td>
        <td>X</td>
        <td></td>
        <td class="path">/api/bindings/<i>vhost</i>/e/<i>source</i>/e/<i>destination</i>/<i>props</i></td>
        <td>
          An individual binding between two exchanges. Similar to
          the individual binding between an exchange and a queue,
          above.
        </tD>
      </tr>
      <tr>
        <td>X</td>
        <td></td>
        <td></td>
        <td></td>
        <td class="path">/api/vhosts</td>
        <td>A list of all vhosts.</td>
      </tr>
      <tr>
        <td>X</td>
        <td>X</td>
        <td>X</td>
        <td></td>
        <td class="path">/api/vhosts/<i>name</i></td>
        <td>An individual virtual host. As a virtual host usually only
        has a name, you do not need an HTTP body when PUTing one of
        these. To enable / disable tracing, provide a body looking like:
          <pre>{"tracing":true}</pre></td>
      </tr>
      <tr>
        <td>X</td>
        <td></td>
        <td></td>
        <td></td>
        <td class="path">/api/vhosts/<i>name</i>/permissions</td>
        <td>A list of all permissions for a given virtual host.</td>
      </tr>
      <tr>
        <td>X</td>
        <td></td>
        <td></td>
        <td></td>
        <td class="path">/api/users</td>
        <td>A list of all users.</td>
      </tr>
      <tr>
        <td>X</td>
        <td>X</td>
        <td>X</td>
        <td></td>
        <td class="path">/api/users/<i>name</i></td>
        <td>An individual user. To PUT a user, you will need a body looking something like this:
<pre>{"password":"secret","tags":"administrator"}</pre>
or:
<pre>{"password_hash":"2lmoth8l4H0DViLaK9Fxi6l9ds8=", "tags":"administrator"}</pre>
        The <code>tags</code> key is mandatory. Either
        <code>password</code> or <code>password_hash</code>
        must be set. Setting <code>password_hash</code> to "" will ensure the
        user cannot use a password to log in. <code>tags</code> is a
        comma-separated list of tags for the user. Currently recognised tags
        are "administrator", "monitoring" and "management".
        </td>
      </tr>
      <tr>
        <td>X</td>
        <td></td>
        <td></td>
        <td></td>
        <td class="path">/api/users/<i>user</i>/permissions</td>
        <td>A list of all permissions for a given user.</td>
      </tr>
      <tr>
        <td>X</td>
        <td></td>
        <td></td>
        <td></td>
        <td class="path">/api/whoami</td>
        <td>Details of the currently authenticated user.</td>
      </tr>
      <tr>
        <td>X</td>
        <td></td>
        <td></td>
        <td></td>
        <td class="path">/api/permissions</td>
        <td>A list of all permissions for all users.</td>
      </tr>
      <tr>
        <td>X</td>
        <td>X</td>
        <td>X</td>
        <td></td>
        <td class="path">/api/permissions/<i>vhost</i>/<i>user</i></td>
        <td>An individual permission of a user and virtual host. To PUT a permission, you will need a body looking something like this:
<pre>{"configure":".*","write":".*","read":".*"}</pre>
        All keys are mandatory.</td>
      </tr>
      <tr>
        <td>X</td>
        <td></td>
        <td></td>
        <td></td>
        <td class="path">/api/parameters</td>
        <td>A list of all parameters.</td>
      </tr>
      <tr>
        <td>X</td>
        <td></td>
        <td></td>
        <td></td>
        <td class="path">/api/parameters/<i>component</i></td>
        <td>A list of all parameters for a given component.</td>
      </tr>
      <tr>
        <td>X</td>
        <td></td>
        <td></td>
        <td></td>
        <td class="path">/api/parameters/<i>component</i>/<i>vhost</i></td>
        <td>A list of all parameters for a given component and virtual host.</td>
      </tr>
      <tr>
        <td>X</td>
        <td>X</td>
        <td>X</td>
        <td></td>
        <td class="path">/api/parameters/<i>component</i>/<i>vhost</i>/<i>name</i></td>
        <td>An individual parameter. To PUT a parameter, you will need a body looking something like this:
<pre>{"vhost": "/","component":"federation","name":"local_username","value":"guest"}</pre>
</td>
      </tr>
      <tr>
        <td>X</td>
        <td></td>
        <td></td>
        <td></td>
        <td class="path">/api/policies</td>
        <td>A list of all policies.</td>
      </tr>
      <tr>
        <td>X</td>
        <td></td>
        <td></td>
        <td></td>
        <td class="path">/api/policies/<i>vhost</i></td>
        <td>A list of all policies in a given virtual host.</td>
      </tr>
      <tr>
        <td>X</td>
        <td>X</td>
        <td>X</td>
        <td></td>
        <td class="path">/api/policies/<i>vhost</i>/<i>name</i></td>
        <td>
          An individual policy. To PUT a policy, you will need a body looking something like this:
<pre>{"pattern":"^amq.", "definition": {"federation-upstream-set":"all"}, "priority":0, "apply-to": "all"}</pre>
          <code>pattern</code> and <code>definition</code> are mandatory, <code>priority</code> and <code>apply-to</code> are optional.
        </td>
      </tr>
      <tr>
        <td>X</td>
        <td></td>
        <td></td>
        <td></td>
        <td class="path">/api/aliveness-test/<i>vhost</i></td>
        <td>
          Declares a test queue, then publishes and consumes a
          message. Intended for use by monitoring tools. If everything
          is working correctly, will return HTTP status 200 with
          body: <pre>{"status":"ok"}</pre> Note: the test queue will
          not be deleted (to to prevent queue churn if this is
          repeatedly pinged).
        </td>
      </tr>
    </table>
  </body>
</html>
